home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Collection of Tools & Utilities
/
Collection of Tools and Utilities.iso
/
dbase
/
softc103.zip
/
SOFTC.DOC
< prev
next >
Wrap
Text File
|
1989-05-11
|
190KB
|
4,535 lines
SoftC (TM) Database Library Reference Manual
Version 1.03
Manual and Software Copyright 1988, 1989
by
K. Schumann
16820 3rd Street North East
Ham Lake, Minnesota 55304
(612) 434-6968
ALL RIGHTS RESERVED
This document describes version 1.03 of the SoftC Database
Library, created in May 1989.
DISCLAIMER
The author makes no representation or warranties with
respect to this product and specifically disclaims any
implied warranties or merchantability or fitness for any
particular purpose. The author shall have no liability with
respect to his obligations under this agreement for
compensatory, special, incidental, consequential, or
exemplary damages.
The author further reserves the right to make changes to the
specifications of the library and contents of the manual
without obligation to notify any person or organizations of
such changes.
Table of Contents
Chapter 1 Introduction....................................1
Registration...........................................2
Registered users are entitled to one free update.......2
Typographic Conventions................................2
Trademarks.............................................3
Support and Updates....................................3
The Future.............................................3
Chapter 2 Before You Begin................................4
The READ.ME File.......................................4
Installing SoftC on Your System........................4
SoftC Applications.....................................5
Compiling with Turbo C.................................5
Compiling with Microsoft C.............................6
Recompiling the SoftC Libraries........................6
Function Naming Conventions............................6
Chapter 3 A dBase III Toolkit Tutorial....................7
Sequential Files.......................................7
Random Access Files....................................7
Keys...................................................7
ISAM and B-trees.......................................8
Basic Rules............................................9
Data File Functions....................................9
Data Record I/O........................................9
Data Field I/O........................................10
Index File Functions..................................11
Index Page Functions..................................11
Index Key Functions...................................11
Chapter 4 Clock & Calendar Functions.....................13
Date String to Date String Conversion.................13
Date String to Numeric Conversion.....................13
Date Numeric to String Conversion.....................13
Date String Calculations..............................13
Date Validation and Testing...........................14
Chapter 5 Miscellaneous Functions........................15
Program Initialization................................15
Program Termination...................................15
Library Version.......................................15
Errors................................................15
Chapter 6 The SoftC Database Library.....................16
sccday................................................18
sccddiff..............................................19
sccdn2s...............................................20
sccds2l...............................................21
sccds2n...............................................21
sccdvalid.............................................22
iii
Table of Contents
sccdxlat..............................................23
sccleap...............................................24
sccleapi..............................................25
sccmonth..............................................26
scdclose..............................................27
scdcreate.............................................28
scdfget...............................................29
scdfgets..............................................31
scdfinfo..............................................32
scdfnam2no............................................34
scdfput...............................................35
scdfputs..............................................36
scdinfo...............................................37
scdopen...............................................38
scdrclear.............................................39
scdrcopy..............................................40
scdrdel...............................................41
scdrget...............................................42
scdrinfo..............................................44
scdrput...............................................45
scdrundel.............................................46
scdsize...............................................47
sceclr................................................48
scemsg................................................49
sciclose..............................................50
scicreate.............................................51
sciexpr...............................................53
sciinfo...............................................54
scikadd...............................................55
scikcur...............................................56
scikdel...............................................57
scikfind..............................................58
scikfirst.............................................60
sciklast..............................................61
scikmake..............................................62
sciknext..............................................65
scikprev..............................................66
scinit................................................67
sciopen...............................................68
scipinfo..............................................69
scipnum...............................................70
scterm................................................71
scvers................................................72
Appendix A License.......................................72
Appendix B Order Form....................................74
Appendix C Revision History..............................75
v1.00 (December of 1988)..............................75
v1.01 (February of 1989)..............................75
iv
Table of Contents
v1.02 (April of 1989).................................76
v1.03 (May of 1989)...................................77
Index....................................................78
v
Chapter 1 Chapter 1
Introduction Introduction
C is generally considered to be a "bare-bones" language. A way to
put some flesh on those bones is to develop generalized functions
(extensions) which may be reused in many programs. The presence
of these functions can make programming a quick and simple task.
The absence of these language extensions can mean many hours lost
"re-inventing the wheel".
Few programmers have the time required to develop and debug such
a library of functions. This is where the SoftC Database Library
comes in. This library is a collection of functions designed to
make your applications quicker and easier to code and test. With
the library you can spend time on your application not on
developing tools.
There also is a benefit to using functions found in a toolkit
library versus using the functions found in your compiler's
library. It may seem trivial, but if you ever decide to change
compilers you will find that it will take many hours to convert
your source to match the new compiler's syntax. Using a generic
toolkit such as SoftC will eliminate that effort.
SoftC adds powerful capabilities to your function library:
-database data and index file functions
-date and time manipulation and calculation
The SoftC Database Library is intended for use as a supplement to
your compiler's object libraries. It contains forty-nine
functions. Its focus is dBaseIII compatible data and index file
manipulation functions. The clock/calendar functions have been
added to enhance the core dBase routines. The library is
currently available for Turbo C 2.0 and Microsoft C 5.1. These
routines were written entirely in C.
The SoftC Database Library is the copyrighted property of K.
Schumann. You are granted a limited license to use the library,
and to copy and distribute the following files (without
modification): SOFTC.H, SCTC20S.LIB, SCMSC51S.LIB, SOFTC.DOC,
READ.ME, LICENSE.DOC and ORDER.DOC.
2 Chapter 1, Introduction 2
Registration Registration
If you find this library useful, you are encouraged to register.
Refer to ORDER.DOC for registration and update fees. To register
read the file LICENSE.DOC, print the file "ORDER.DOC", and mail
the completed form to:
Kim L. Schumann
16820 3rd Street North East
Ham Lake, Minnesota 55304
Registered users are entitled to one free update.
Shareware Shareware
This library is "shareware" (user supported software) NOT "public
domain". Which means that the library is the copyrighted property
of the author, but you are granted the right to make copies and
distribute it (under the conditions specified above) to anyone at
no cost. They are in turn requested to register if they decide to
use it.
The shareware concept is an attempt to provide useful software at
low cost. The expense of offering a new product by conventional
means is quite high and thus discourages many independent authors
and small companies from developing and promoting their ideas.
Shareware is an attempt to develop a new marketing channel where
products can be introduced at minimum cost.
Everyone will benefit if shareware works. The user benefits by
receiving quality products at low cost, and by being able to test
software thoroughly before purchasing it. The author benefits by
being able to enter the commercial software market without the
need of large amounts of venture capital.
But it can only work with your support. If you obtain a user
supported product from a friend or coworker, and are still using
it after a couple of weeks, then it is obviously worth something
to you, and a contribution should be sent.
Typographic Conventions Typographic Conventions
[] Square brackets enclose optional data.
Boldface SoftC Library function names (such as Boldface
scinit) and structure names when they scinit
appear in text (but not in program
examples).
Chapter 1, Introduction 3 3
Italics indicate variable names (identifiers) that _______ ___________
appear in text.
Trademarks Trademarks
Clipper is a registered trademark of Nantucket Software.
dBASEIII is a registered trademark of Ashton-Tate.
Microsoft is a registered trademark of Microsoft Corporation.
SoftC is a trademark of K. Schumann
Turbo C is a registered trademark of Borland International.
Support and Updates Support and Updates
I will only offer advice and technical support to those who
contribute via the shareware concept. Users who register will be
notified when updates and new products are available.
I can be contacted by telephone at (612) 434-6968 after 6pm
Central Time, via mail at the registration address above, or on
GEnie through GE Mail at "K.SCHUMANN".
The Future The Future
There are many enhancements that could be made to the dBaseIII
routines: make them LAN multi-user, add functions found in dBase
which do not have a corresponding C function, and add support for
dBaseIII MEMO fields. Extensions could be added to enable dBaseIV
file access.
Anyone wishing to offer advice and suggestions are most welcome
to do so.
Chapter 2 Chapter 2
Before You Begin Before You Begin
This chapter supplies instructions for installing the library on
your hard disk and compiling the source.
The READ.ME File The READ.ME File
For last minute update information not contained in this
documentation, and/or a brief description of what's new with this
release please read the READ.ME file found on the library
diskette (or if you have the demonstration version of the library
it will be found in the .ARC file).
Installing SoftC on Your System Installing SoftC on Your System
The SoftC Library source code is compatible with all of the
compilers which I support. The object code diskette is for your
specific compiler. Check the label on this diskette to be sure it
is the correct one. It is a good idea to recompile the library
when you upgrade your compiler.
Many compiler manufacturers suggest a certain directory setup to
enable the compiler to find the header, object, and library
files. Rather than trying to explain the various manufacturers
suggested directory setups, I will explain what files are
required and where they are often located.
The SoftC header files need to be placed where they can be found
by your compiler. In many cases this is in a special "INCLUDE"
directory. Other times they are placed where your source code is
found. I would suggest that they be placed where the header files
for your compiler are located. All the header files will be found
on the source code diskette.
Your linker will need to be able to find the SoftC object
libraries. It is suggested that these be placed where the run-
time libraries for your compiler are found. These libraries will
be found on the library diskette.
The name of the library defines the compiler manufacturer and
version, and the memory model for which it was compiled. All
library names begin with "SC". The next few characters specify
Chapter 2, Before You Begin 5 5
the compiler manufacturer. The last character defines the memory
model.
For example SCTC20S.LIB is the small memory model library for
Borland's Turbo C compiler (version 2.x).
SoftC Applications SoftC Applications
A typical application skeleton has the following form:
#include <softc.h>
/* global declarations */
void main()
{
/* local declarations */
scinit(20);
.
.
.
/* body of application */
.
.
.
scterm();
}
The scinit function must be the first function called in your scinit
application and IT MUST BE CALLED ONLY ONCE. The last function IT MUST BE CALLED ONLY ONCE
should be scterm. This is not a requirement but it is good scterm
programming practice. This function should be called only once.
See the descriptions of these functions in the library reference
section of this manual.
Compiling with Turbo C Compiling with Turbo C
Turbo C provides two ways of compiling programs: the integrated
environment and the command line version. In order to use SoftC
with the integrated environment a project file must be created
and the appropriate library must be specified in that file:
6 Chapter 2, Before You Begin 6
myprog /* your program name */
sctc20s.lib /* the desired SoftC library */
To use the library with the command line compiler simply include
the library name in filename list:
tcc -ml -I<header file path> -L<lib file path> myprog sctc20s.lib
Compiling with Microsoft C Compiling with Microsoft C
To use the library with Microsoft's command line compiler simply
include the library name in filename list:
cl /AL /Zp myprog scmsc51s.lib
Recompiling the SoftC Libraries Recompiling the SoftC Libraries
If you modify a SoftC source code file, then that module and any
related modules (if any) must be recompiled and replaced in the
libraries. The library source code is compiled just like any
other SoftC program.
Turbo C command line:
tcc -c -ml -I<header file path> -f *.c
Microsoft C command line:
cl /AL /c /Zp /W3 *.c
Refer to your compiler documentation for instructions for
replacing modules in libraries. Batch files are included with the
source code to assist you in rebuilding the libraries.
Function Naming Conventions Function Naming Conventions
All SoftC functions begin with the letters "sc". This is to
differentiate them from the standard library functions. The dBase
III data file functions begin with "scd", the dBase III index
file functions with "sci", and the clock/calendar functions with
"scc".
Chapter 3 Chapter 3
A dBase III Toolkit Tutorial A dBase III Toolkit Tutorial
Most applications need to do some file I/O operations. Your C
compiler provides you with basic functions to do general file
I/O. But many cases will arise when you need to use a database
within your application. The SoftC Database Library provides
functions to enable you to integrate your program and dBase III
compatible data and index files.
For those of you who may be unfamiliar with databases, think of a
filing cabinet filled with folders of invoices ordered
alphabetically by company name. If we wish to put this
information "on computer" we have two choices for data file I/O:
a simple sequential file, or a random access file.
Sequential Files Sequential Files
The concept of using a sequential file to store invoice data by
company name is very simple. Just enter the data as it's found in
the filing cabinet. To access the information just begin reading
at the start of the file and continue until finished. As you can
see the time required to find a specific record greatly increases
as more and more records are added to the file. Also the act of
adding information to the file while trying to keep it in
alphabetical order becomes very time consuming due to the fact
that many records will have to be moved in order to make room for
the new record.
Random Access Files Random Access Files
By using random access techniques it becomes much easier to
access any particular data record. All that is required is the
desired record number and you can seek to the proper location
within the data file. But how do you know which record number to
use? And what about adding records in the middle of the data
file? dBase uses keys and an indexed lookup system called ISAM to
solve both of these problems.
Keys Keys
Keys are generally comprised of one or more pieces of information
(data fields) found in a data record. In our example the company
name could be used as a key. Each key would point to one or more
records found in the data file. When many keys are grouped
8 Chapter 3, A dBase III Toolkit Tutorial 8
together they form an index file. dBase uses a technique called
ISAM to access the underlying B-tree structure of its index
files.
ISAM and B-trees ISAM and B-trees
The relationship between a key and the data file record number is
established via a "key item". Many key items are found on an
"index page". Many index pages are combined to form an "index
file". The method used to navigate through the index file is
called "Indexed Sequential Access Method" or ISAM. B-tree (or
branch tree) is the underlying structure used in ISAM. Searching
always begins at the top of the tree. Each key item on an index
page can point to another index page (this is where the
"branching" comes into play). If a key item does not point to
another index page it is referred to as a "terminal node". A
search is ended when a terminal node is encountered.
When a data record for a specific key needs to be accessed, The
first (top) index page is searched with the desired key text. If
not at a terminal node, a determination will be made using the
branch trees as to which index page should next be searched. This
sequence of searching and branching is followed until a terminal
node is encountered. If an exact match is found the data record
number present in that key item can be used to access the data
file.
When a key needs to be added to an index file, the above sequence
of searching and branching is again followed until the location
where the new key should be placed is found. Because of the
nature of the ISAM file it is much easier and faster to add a key
to the index page than appearances may indicate. If an index page
overflows it will be split into two pages. Likewise if it
underflows it will be joined with another index page. This system
results in a minimal amount of file I/O.
The first question above has been obviously answered, but what
about the second? The answer lies in the fact that because we are
using an index file we no longer have to keep the data file in
alphabetical order, all we need to do is append records to the
end of the data file and add a key to the index file.
This ends the general discussion of databases. One note, it is
good programming practice to create keys only from data fields
found in the data record, this allows the reconstruction of an
index file should something catastrophic happen.
Chapter 3, A dBase III Toolkit Tutorial 9 9
Basic Rules Basic Rules
In order to benefit fully from the SoftC Database Library, it is
necessary to use only the functions found in the library when
performing database I/O. When standard functions such as fprintf fprintf
are used, the SoftC database manager is bypassed. This means that
it can no longer keep track of the activities in your database
files which can lead to unpredictable results.
This is not to say that you cannot use the standard C file I/O
functions found in your compiler's libraries, but their use
should be restricted to non-database I/O.
Data File Functions Data File Functions
In order to use a data file it first must be opened. scdopen will scdopen
open any dBase III or dBase III+ compatible data file. The SoftC
database manager file handle will be returned. This handle number
must be used for all I/O with that specific data file.
When you are finished with a data file it is good practice to
close that data file via a call to scdclose. This is true for a scdclose
couple of reasons: 1) The data will be safe if your application
crashes, and 2) computer memory will be freed for other use. A
safety net is provided by scterm in that it will close all data scterm
and index files open at program termination.
The length of the data file in bytes can be found using scdsize. scdsize
The name of the data file associated with a particular handle can
be retrieved via a call to scdinfo. Also a new data file can be scdinfo
created by scdcreate. scdcreate
Data Record I/O Data Record I/O
Having a data file is of little use unless you can manipulate the
individual records. SoftC provides seven functions to: read/write
individual records, delete/recover deleted records, manipulate
I/O buffers, and retrieve information about the record structure.
A data record can be read from the data file using scdrget. The scdrget
actual data will be placed in a SoftC internal buffer. See the
discussion on Data Field I/O for more information on accessing
the individual fields found in a data record. When a data record
needs to be written to the file, scdrput should be used. This scdrput
function is used both for the changing of a record as well as
adding new records.
10 Chapter 3, A dBase III Toolkit Tutorial 10
dBase III data records are not physically removed from the data
file when they are deleted. This enables the user to change his
mind and recover the deleted records for use again. SoftC follows
this guideline by providing the scdrdel function to mark a data scdrdel
record as deleted, and the scdrundel function to recover the scdrundel
record (or mark as active).
Information about the data record structure can be retrieved by a
called to scdrinfo. The record length, number of fields in the scdrinfo
data record, and the addresses of the I/O buffers can be obtained
in this way.
Two additional functions are provided which deal exclusively with
the internal SoftC I/O buffers: scdrclear, and scdrcopy. scdrclear scdrcopy
scdrclear is useful in clearing the output buffer before placing scdrclear
data in the individual fields. The entire data record will be set
to spaces (" "). This has the effect on numeric fields of placing
nothing in the field rather than zero. scdrcopy can be useful scdrcopy
when a record needs to be updated but the original also needs to
be retained.
Data Field I/O Data Field I/O
The six data field manipulation functions provide for: the
writing of data to a field in the output buffer, the reading of
data from a field in the input buffer, the conversion of field
names to field numbers, and the retrieval of the field
descriptions originally setup with scdcreate. scdcreate
There are two types of field I/O: standard C types and ASCIIZ
string. scdfput and scdfget use the standard C types below to scdfput scdfget
place data in and retrieve data from individual fields in a
record. scdfput attempts to properly format the data before scdfput
placing it in the field. This means that the proper number of
spaces, zeros, and/or a decimal point will be added as
appropriate.
C types dBase III types
char [9] date
ASCIIZ string character
double numeric
char logical
scdfputs and scdfgets use ASCIIZ strings exclusively. It is left scdfputs scdfgets
up to the users of these functions to ensure that the data is
properly formatted. Both "scdfput" functions work with the output
buffer, and the "scdfget" functions work with the input buffer.
Chapter 3, A dBase III Toolkit Tutorial 11 11
A field name to field number translation function (scdfnam2no) is scdfnam2no
provided to isolate your application from the structure of the
data files.
Index File Functions Index File Functions
In order to use an index file it first must be opened. sciopen sciopen
will open any dBase III or dBase III+ compatible index file. The
index files created by Clipper are not compatible with dBase III
(and thusly with this library). The SoftC database manager file
handle will be returned. This handle number must be used for all
I/O with that specific index file.
When you are finished with an index file, it can be closed via a
call to sciclose. Information about the index file such as the sciclose
file name and length of the key expression can be retrieved by a
call to sciinfo. A new index file can be created by using the sciinfo
function scicreate. scicreate
sciexpr can be used to get the actual index key expression. This sciexpr
key expression is generally a formula listing the field names
used to make the index key. For example, FIRST_NAME and LAST_NAME
are both fields found in a data file, if an index key was made
from the combination of these fields the key expression could be
"LAST_NAME + FIRST_NAME".
Index Page Functions Index Page Functions
If memory is available the SoftC database manager will allocate
space for ten index pages. In some instances more or less pages
may be needed to provide fast access to index information.
scipinfo is used to find out how many pages for which space was scipinfo
allocated. To change the number of pages for which memory was
allocated, scipnum can be used. scipnum
Index Key Functions Index Key Functions
Nine functions have been provided for use in: finding a key,
moving to the next or previous key, adding/deleting a key,
retrieving the current key, and building a key. There are three
search functions supported: find first key (scikfirst), finding scikfirst
the last key (sciklast), and searching for a specific key sciklast
(scikfind). The keys found in this manner become the "current scikfind
key". Wildcards such as "?" and "*" cannot be used.
Once a particular key is found it is often desired to get the key
following (sciknext) or the key preceding (scikprev) it. These sciknext scikprev
12 Chapter 3, A dBase III Toolkit Tutorial 12
keys, if found, become the current key. Another function is
provided to return the current key, scikcur. scikcur
It also desirable to be able to add and delete keys from the
index file. scikadd and scikdel provide these functions. These scikadd scikdel
functions also attempt to keep the B-tree balanced, so that one
branch of the tree will not grow larger than the others.
dBaseIII provides certain functions which may be used in a key
expression. scikmake will build a key for you using the index key scikmake
expression and the contents of the current output buffer. This
function supports five of the more common dBaseIII functions:
dtoc, left, right, str, and substr (and the various legitimate dtoc left right str substr
combinations of them). Note that this function is not necessary
for single field character or numeric keys, but it should be used
for date keys.
Chapter 4 Chapter 4
Clock & Calendar Functions Clock & Calendar Functions
This chapter will describe the date functions available in the
SoftC Database Library. Currently there are ten functions
implemented. Note that the date format is "yyyymmdd" for all
functions unless otherwise specified.
Date String to Date String Conversion Date String to Date String Conversion
Internal to dBaseIII the date fields are formatted as "yyyymmdd".
This format enables the date field to be used properly as an
index key and ensures that the date February 13, 1989 will always
be larger than the date December 15, 1988. Note that this date
format is not the one normally used when entering or displaying
dates. If fact dBaseIII uses the date format "mm/dd/yy" when it
displays dates.
A function sccdxlat was created to allow switching between these sccdxlat
two formats. An additional format is provided to enable the year
section of the date to more accurately represent the year
entered. This format is "mm/dd/yyyy".
Date String to Numeric Conversion Date String to Numeric Conversion
Along with character string dates, SoftC supports two types of
numeric dates: year, month, and day in integer form, and number
of elapsed days in long integer form. sccds2n is used to convert sccds2n
from a character string to integers, and sccds2l will convert sccds2l
from string to long integer.
Date Numeric to String Conversion Date Numeric to String Conversion
SoftC also supports the conversion to character strings, where
sccdn2s converts integers to a string. Two additional functions sccdn2s
are included to return character strings for an integer day
(sccday) or month (sccmonth) input, for example "Thursday", or sccday sccmonth
"March".
Date String Calculations Date String Calculations
sccddiff will compute the difference in days between two dates. sccddiff
14 Chapter 4, Clock & Calendar Functions 14
Date Validation and Testing Date Validation and Testing
Two functions are provided to test for leap year: one requires a
character string as input (sccleap) and the other an integer sccleap
(sccleapi). Also sccdvalid can be used to check the validity of a sccleapi sccdvalid
date string.
Chapter 5 Chapter 5
Miscellaneous Functions Miscellaneous Functions
This chapter will describe the miscellaneous functions found in
the SoftC Database Library.
Program Initialization Program Initialization
scinit sets up the SoftC database manager. Memory will be scinit
allocated for a variety of internal structures. As previously
mentioned this function should be called only once at the
beginning of your application.
Program Termination Program Termination
scterm is called at the end of your application. It will close scterm
all database files and free the memory allocated by scinit. scinit
Library Version Library Version
The scvers function has been provided to retrieve a NULL scvers
terminated character string containing the version of the SoftC
library you are currently using. This can then be printed by
puts. puts
Errors Errors
A global variable sc_code will contain the results of the last sc_code
SoftC function call executed. Errors are indicated by negative
numbers, warnings by positive numbers greater than zero, and a
zero indicates success. During program debug it may be
advantageous to print the text message associated with the
contents of sc_code. scemsg will return the address of the sc_code scemsg
message associated with the contents of sc_code, which can then sc_code
be printed by puts. puts
If you desire to clear an error or warning condition either the
global variable sc_code can be set to zero or the function sceclr sc_code sceclr
can be used. It is preferable to use the function rather than the
global variable.
Chapter 6 Chapter 6
The SoftC Database Library The SoftC Database Library
This chapter contains a detailed description of each of the
functions in the library.
The following sample function description explains how to use
this portion of the SoftC Database Library Reference Manual.
function name function name _____________
Usage Usage _____
function(modifier parameter[,...]); function _________
The declaration syntax for function, parameter names function _________
are italicized. The [,...] indicates that other
parameters and their modifiers may follow.
Prototype in Prototype in ____________
This lists the header files in which the function is
prototyped.
Description Description ___________
This describes what the function does, the parameters
it takes, and any details you need in order to use
function and the related routines listed.
See also See also ________
Routines related to the function about which you may
wish to read are listed here.
Return Value Return Value ____________
The value(s) that the function returns (if any) are
listed here. The return value will also be set in
sc_code. Unless otherwise noted in the specific sc_code
function description, the function call will be ignored
if sc_code contains an error (values less than zero). A sc_code
good return will always be equal to zero. Any warning
codes are always greater than zero.
Chapter 6, The SoftC Database Library 17 17
Example Example _______
A sample program listing demonstrating how the function
is used.
18 Chapter 6, The SoftC Database Library 18
sccday sccday ______
Usage Usage _____
signed short int sccday( signed char day, sccday ___
signed char daystr[10] ); ______
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
sccday returns the day of the week string in daystr for sccday ______
the day specified by day. day must be in the range of 0 ___ ___
(Sunday) to 6 (Saturday). The maximum length of the
string returned will be 9 plus the NULL byte.
See also See also ________
sccmonth sccmonth
Return Value Return Value ____________
SC_SUCCESS function successful
SC_BADDATE invalid date
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char day[10];
scinit(1);
sccday(0,day);
puts(day);
scterm();
}
Chapter 6, The SoftC Database Library 19 19
sccddiff sccddiff ________
Usage Usage _____
signed short int sccddiff( signed char *date1, sccddiff _____
signed char *date2, _____
signed long *diff ); ____
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
sccddiff returns the difference in days between date1 sccddiff _____
and date2. The two date strings can be in any order, _____
but must be valid dates of the format "yyyymmdd" (eg
"19890213"). This is the date format used internally by
the SoftC database manager. sccdxlat can be used to sccdxlat
translate an existing date string to this format, or a
date string can be built using sccdn2s. sccdn2s
See also See also ________
sccdxlat, sccdn2s, sccdvalid. sccdxlat sccdn2s sccdvalid
Return Value Return Value ____________
SC_SUCCESS calculation successful
SC_BADDATE invalid date
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
signed long d;
scinit(1);
sccddiff("19890213","19881217",&d);
printf("%ld",d);
scterm();
}
20 Chapter 6, The SoftC Database Library 20
sccdn2s sccdn2s _______
Usage Usage _____
signed short int sccdn2s( signed int year, sccdn2s ____
signed int month, _____
signed int day, ___
signed char *string ); ______
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
sccdn2s converts three integer date values (year, sccdn2s ____
month, and day) into a character string (string). A _____ ___ ______
check is made to verify that string is a valid date ______
string before exiting.
See also See also ________
sccdvalid, sccds2n. sccdvalid sccds2n
Return Value Return Value ____________
SC_SUCCESS conversion successful
SC_BADDATE invalid date
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
signed char d[9];
scinit(1);
sccdn2s(1989,2,13,d);
puts(d);
scterm();
}
Chapter 6, The SoftC Database Library 21 21
sccds2l sccds2l _______
Usage Usage _____
signed short int sccds2l( signed char *string, sccds2l ______
signed long *date ); ____
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
sccds2l converts a character string (string) into a sccds2l ______
long date. ____
Return Value Return Value ____________
SC_SUCCESS conversion successful
SC_BADDATE invalid date
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
signed long l;
scinit(1);
sccds2l("19890323",&l);
printf("%ld",l);
scterm();
}
sccds2n sccds2n _______
Usage Usage _____
signed short int sccds2n( signed char *string, sccds2n ______
signed int *year, ____
signed int *month, _____
signed int *day ); ___
22 Chapter 6, The SoftC Database Library 22
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
sccds2n converts dates from a character string (string) sccds2n ______
to three integer values (year, month, and day). A ____ _____ ___
partial check is made to verify that string is a valid ______
date string before attempting to convert.
See also See also ________
sccdn2s. sccdn2s
Return Value Return Value ____________
SC_SUCCESS conversion successful
SC_BADDATE invalid date
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
signed int y, m, d;
scinit(1);
sccds2n("19890213",&y,&m,&d);
printf("%d %d %d",y,m,d);
scterm();
}
sccdvalid sccdvalid _________
Usage Usage _____
signed short int sccdvalid( signed char *string ); sccdvalid ______
Prototype in Prototype in ____________
SoftC.h
Chapter 6, The SoftC Database Library 23 23
Description Description ___________
sccdvalid tests the date string (string) passed for sccdvalid ______
validity: string properly formatted ("yyyymmdd"), valid
day of month, valid month of year.
Return Value Return Value ____________
SC_SUCCESS valid date
SC_BADDATE invalid date
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
scinit(1);
if (sccdvalid("19890213") == SC_SUCCESS)
puts("Good Date.");
else
puts("Bad Date.");
scterm();
}
sccdxlat sccdxlat ________
Usage Usage _____
signed short int sccdxlat( signed char method, sccdxlat ______
signed char *source, ______
signed char *dest ); ____
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
sccdxlat translates from one date string format to sccdxlat
another under control of method. Currently three ______
translation methods are supported: SC_2ASCII - from
"yyyymmdd" to "mm/dd/yy", SC_2ASCIIL - from "yyyymmdd"
to "mm/dd/yyyy", and SC_2DBASE - from "mm/dd/[yy]yy" to
"yyyymmdd".
24 Chapter 6, The SoftC Database Library 24
The maximum lengths of dest and source are 10 ____ ______
characters (plus the NULL byte).
Note that when converting using SC_2DBASE dates such as
"2/1/89" will be translated to "19890201".
Return Value Return Value ____________
SC_SUCCESS translation successful
SC_BADCMD invalid translation method ______
SC_BADDATE invalid date
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char date[11];
scinit(1);
sccdxlat(SC_2ASCII,"2/1/89",date);
puts(date);
scterm();
}
sccleap sccleap _______
Usage Usage _____
signed short int sccleap( signed char *leap ); sccleap ____
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
sccleap tests the string year passed to it in leap to sccleap ____
see if it is a leap year.
See also See also ________
sccleapi sccleapi
Chapter 6, The SoftC Database Library 25 25
Return Value Return Value ____________
> 0 year was a leap year
SC_SUCCESS year was not a leap year
SC_BADDATE invalid date
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
scinit(1);
if (sccleap("1989")
puts("Leap Year!");
else
puts("Normal Year.");
scterm();
}
sccleapi sccleapi ________
Usage Usage _____
signed short int sccleapi( signed int leap ); sccleapi ____
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
sccleapi tests the integer year passed to it in leap to sccleapi ____
see if it is a leap year.
See also See also ________
sccleap sccleap
Return Value Return Value ____________
> 0 year was a leap year
SC_SUCCESS year was not a leap year
SC_BADDATE invalid date
SC_NULLPARM parameter address null
26 Chapter 6, The SoftC Database Library 26
Example Example _______
#include "SoftC.h"
void main()
{
scinit(1);
if (sccleap(1989)
puts("Leap Year!");
else
puts("Normal Year.");
scterm();
}
sccmonth sccmonth ________
Usage Usage _____
signed short int sccmonth( signed char month, sccmonth _____
signed char monthstr[10] ); ________
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
sccmonth returns the month string in monthstr for the sccmonth ________
month specified by month. month must be in the range of _____ _____
1 (January) to 12 (December). The maximum length of the
string returned will be 9 plus the NULL byte.
See also See also ________
sccday sccday
Return Value Return Value ____________
SC_SUCCESS function successful
SC_BADDATE invalid date
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
Chapter 6, The SoftC Database Library 27 27
void main()
{
char month[10];
scinit(1);
sccmonth(4,month);
puts(month);
scterm();
}
scdclose scdclose ________
Usage Usage _____
signed short int scdclose( signed char handle ); scdclose ______
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdclose closes a .DBF file and frees all allocated scdclose
memory associated with .DBF file handle.
See also See also ________
scdopen scdopen
Return Value Return Value ____________
SC_SUCCESS .DBF file closed
SC_CLOSFAIL file close failure
SC_BADHNDL .DBF file not open or bad handle
Example Example _______
#include "SoftC.h"
void main()
{
char dbf;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS)
scdclose(dbf);
28 Chapter 6, The SoftC Database Library 28
scterm();
}
scdcreate scdcreate _________
Usage Usage _____
signed short int scdcreate( signed char *filename, scdcreate ________
signed char numfields, _________
SC_FIELD fields[]); ______
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdcreate creates a .DBF file. A pointer to an array of scdcreate
SC_FIELD must be passed.
typedef struct {
signed char name[11]; /* field name */
signed char type; /* field type */
unsigned char len; /* field length */
unsigned char decpl; /* decimal places */
} SC_FIELD; SC_FIELD
The field description array must be initialized and
each element set to appropriate values. The array
determines the organization of a data record. The .DBF
file does not remain open upon exit of this function.
This function will create a new .DBF file even if one
had already existed.
Field names and types are converted to all upper case
when the file is created.
Restrictions:
maximum record length is 4000 bytes.
maximum number of fields is 128.
maximum length of character fields is 254.
maximum length of numeric fields is 19 this includes
Chapter 6, The SoftC Database Library 29 29
the decimal point and the sign .
length of date field is forced to 8.
length of logical fields is forced to 1.
the decimal places will be forced to zero for all types
except NUMERIC in which case it must be less then 'len'
- 2.
Return Value Return Value ____________
SC_SUCCESS .DBF file created
SC_WRTFAIL disk write failure
SC_BADFLD user supplied field description bad
SC_NOHNDL no DOS file handles available
SC_NULLPARM parameter address null
SC_MEMOFLD memo fields are not fully supported
Example Example _______
#include "SoftC.h"
void main()
{
SC_FIELD fields[4] = {
"character",'c',16,0, /* character field */
"date",'d',8,0, /* date field */
"logical",'l',1,0, /* logical field */
"numeric",'n',6,2 /* numeric field */
};
scinit(20);
scdcreate("TEST.DBF",4,fields);
scterm();
}
scdfget scdfget _______
Usage Usage _____
signed short int scdfget( signed char handle, scdfget ______
signed char fieldno, _______
void *data ); ____
Prototype in Prototype in ____________
dbase.h
30 Chapter 6, The SoftC Database Library 30
Description Description ___________
scdfget gets data from the desired field (fieldno) of scdfget _______
the input buffer. data will be converted from DBaseIII
to a more natural data type for 'c':
DBaseIII field type returned data type
'C' signed char *
'D' signed char [9]
'L' signed char
'N' double
scdfinfo can be used to determine the length of the scdfinfo
longest data field in the file.
Note that date fields are returned as NULL terminated
character strings in the form: "mm/dd/yy", and
character fields are returned as NULL terminated
character strings.
See also See also ________
scdfgets, scdfput, scdfinfo, scdrget. scdfgets scdfput scdfinfo scdrget
Return Value Return Value ____________
SC_SUCCESS retrieved data from field
SC_BADHNDL .DBF file not open or bad handle
SC_BADFLD invalid data record field number
SC_NULLPARM parameter address null
SC_MEMOFLD memo fields are not fully supported
Example Example _______
#include "SoftC.h"
void main()
{
char dbf, character[17],logical,date[9];
double numeric;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdrget(dbf,1L);
scdfgets(dbf,0,character);
scdfget(dbf,1,(void *) date);
scdfget(dbf,2,(void *) &logical);
scdfget(dbf,3,(void *) &numeric);
printf("%s %s %c %lf\n",
Chapter 6, The SoftC Database Library 31 31
character,date,logical,numeric);
scdclose(dbf);
}
scterm();
}
scdfgets scdfgets ________
Usage Usage _____
signed short int scdfgets( signed char handle, scdfgets _______
signed char fieldno, _______
char *data ); ____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdfgets gets data from the desired field (fieldno) of scdfgets _______
the input buffer. data will be returned as an ASCIIZ ____
string.
scdfinfo can be used to determine the length of the scdfinfo
longest data field in the file.
Note that date fields are returned in the form
"yyyymmdd". There is a difference between the date
formats of scdfgets and scdfget. scdfgets scdfget
See also See also ________
scdfget, scdfputs, scdfinfo, scdrget. scdfget scdfputs scdfinfo scdrget
Return Value Return Value ____________
SC_SUCCESS retrieved data from field
SC_BADHNDL .DBF file not open or bad handle
SC_BADFLD invalid data record field number
SC_NULLPARM parameter address null
SC_MEMOFLD memo fields are not fully supported
32 Chapter 6, The SoftC Database Library 32
Example Example _______
#include "SoftC.h"
void main()
{
char dbf, character[17], logical, date[9];
double numeric;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdrget(dbf,1L);
scdfgets(dbf,0,character);
scdfgets(dbf,1,date);
scdfget(dbf,2,(void *) &logical);
scdfget(dbf,3,(void *) &numeric);
printf("%s %s %c %lf\n",
character,date,logical,numeric);
scdclose(dbf);
}
scterm();
}
scdfinfo scdfinfo ________
Usage Usage _____
signed short int scdfinfo( signed char handle, scdfinfo ______
signed char *longfldlen, __________
SC_FIELD *fields ); ______
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdfinfo copies the .DBF field descriptions to fields scdfinfo ______
using the structure SC_FIELD. The length of the longest SC_FIELD
data field is also returned (longfldlen). __________
typedef struct {
signed char name[11]; /* field name */
signed char type; /* field type */
unsigned char len; /* field length */
Chapter 6, The SoftC Database Library 33 33
unsigned char decpl; /* decimal places */
} SC_FIELD; SC_FIELD
The user must ensure that the array defined for fields
is large enough to hold all of the field descriptions
because scdfinfo blindly copies the descriptions to scdfinfo
fields. Severe program errors can be the result if the
field array is too small. Use scdrinfo to determine the scdrinfo
number of fields in the data record.
See also See also ________
scdrinfo scdrinfo
Return Value Return Value ____________
SC_SUCCESS returned the field descriptions
SC_BADHNDL .DBF file not open or bad handle
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char dbf, longfld, numflds, a;
SC_FIELD fields[128]; /* dBaseIII max size */
short reclen;
void *ibfr, *obfr;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdrinfo(dbf,&reclen,&numflds,&ibfr,&obfr);
scdfinfo(dbf,&longfld,fields);
printf("longest field length = %d\n",longfld);
for (a = 0; a < numflds; a++)
printf("%s %c %d %d\n", fields[a].name, fields[a].type,
fields[a].len, fields[a].decpl);
scdclose(dbf);
}
scterm();
}
34 Chapter 6, The SoftC Database Library 34
scdfnam2no scdfnam2no __________
Usage Usage _____
signed short int scdfnam2no( signed char handle, scdfnam2no ______
signed char *fieldname, _________
signed char *fieldno ); _______
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdfnam2no searches through the field description array scdfnam2no
for .DBF file handle looking for fieldname. It will ______ _________
return the corresponding field number.
Note that .DBF files created by SoftC will have field
names changed to all upper case.
Return Value Return Value ____________
SC_SUCCESS field number returned
SC_BADHNDL .DBF file not open or bad handle
SC_BADFLD invalid data record field name
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char dbf, fldno
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdfnam2no(dbf,"LOGICAL",&fldno);
printf("%d",fldno);
scdclose(dbf);
}
scterm();
}
Chapter 6, The SoftC Database Library 35 35
scdfput scdfput _______
Usage Usage _____
signed short int scdfput( signed char handle, scdfput ______
signed char fieldno, _______
void *data ); ____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdfput will convert data from 'c' format to dBaseIII scdfput ____
format and place it in the proper field (fieldno) of _______
the output buffer.
Field numbers begin with zero (0). If the field is
numeric, data should be passed as a double. ____
Note that scdfput follows the date formatting standard scdfput
of scdfget. It is optional to include the "19" from scdfget
"1989" as this is assumed, however the date "2/1/00"
will become "19000201" even if you had intended it to
be "20000201". Date strings can be formatted as
"2/1/2000" to overcome this problem.
See also See also ________
scdfget, scdfputs. scdfget scdfputs
Return Value Return Value ____________
SC_SUCCESS data placed in field
SC_BADHNDL .DBF file not open or bad handle
SC_BADFLD invalid data record field number
SC_NULLPARM parameter address null
SC_BADDATE invalid date field
SC_FLDTRUNC character field truncated
Example Example _______
#include "SoftC.h"
void main()
{
36 Chapter 6, The SoftC Database Library 36
char dbf, logical = 'T', date[9] = "12/25/88";
long recno;
double numeric = 20.0L;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdfputs(dbf,0,"SoftC Library ");
scdfput(dbf,1,(void *) date);
scdfput(dbf,2,(void *) &logical);
scdfput(dbf,3,(void *) &numeric);
scdrput(dbf,SC_ADD,&recno);
printf("Record number = %ld\n",recno);
scdclose(dbf);
}
scterm();
}
scdfputs scdfputs ________
Usage Usage _____
signed short int scdfputs( signed char handle, scdfputs ______
signed char fieldno, _______
char *data ); ____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdfputs will place data in the proper field (fieldno) scdfputs ____ _______
of the output buffer. It is the user's responsibility
to provide a properly sized and formatted ASCIIZ string
to scdfputs. scdfputs
Field numbers begin with zero (0). If the field is
numeric, data should be passed as a double. ____
Note that scdfputs follows the date formatting scdfputs
conventions of scdfgets. Also be aware that the date scdfgets
formatting conventions of scdfget/scdfput are not the scdfget scdfput
same as scdfgets/scdfputs. scdfgets scdfputs
Chapter 6, The SoftC Database Library 37 37
See also See also ________
scdfgets, scdfput. scdfgets scdfput
Return Value Return Value ____________
SC_SUCCESS data placed in field
SC_BADHNDL .DBF file not open or bad handle
SC_BADFLD invalid data record field number
SC_NULLPARM parameter address null
SC_BADDATE invalid date field
SC_FLDTRUNC character field truncated
Example Example _______
#include "SoftC.h"
void main()
{
char dbf, logical,date[9];
long recno;
double numeric;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdfputs(dbf,0,"SoftC Library ");
scdfputs(dbf,1, date);
scdfput(dbf,2,(void *) &logical);
scdfput(dbf,3,(void *) &numeric);
scdrput(dbf,SC_ADD,&recno);
printf("Record number = %ld\n",recno);
scdclose(dbf);
}
scterm();
}
scdinfo scdinfo _______
Usage Usage _____
signed short int scdinfo( signed char handle, scdinfo ______
signed char *filename ); ________
Prototype in Prototype in ____________
dbase.h
38 Chapter 6, The SoftC Database Library 38
Description Description ___________
scdinfo gets the name of the file associated with scdinfo
handle. ______
See also See also ________
scdopen scdopen
Return Value Return Value ____________
SC_SUCCESS returned the file name
SC_BADHNDL .DBF file not open or bad handle
SC_NULLPARM parameter address null
Example Example _______
#include <dir.h>
#include "SoftC.h"
void main()
{
char dbf;
char filename[MAXPATH];
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdinfo(dbf,filename);
printf("%s",filename);
scdclose(dbf);
}
scterm();
}
scdopen scdopen _______
Usage Usage _____
signed short int scdopen( signed char *handle, scdopen ______
signed char *filename ); ________
Prototype in Prototype in ____________
dbase.h
Chapter 6, The SoftC Database Library 39 39
Description Description ___________
scdopen opens a .DBF file. Memory will be allocated for scdopen
a file packet and I/O buffers for use internally by the
SoftC file manager.
Return Value Return Value ____________
SC_SUCCESS file opened and memory allocated
SC_MEMERR memory allocation failure
SC_NOFILE .DBF file not found
SC_RDFAIL disk read failure
SC_NODBF file not in .DBF format
SC_SKFAIL disk seek failure
SC_NOHNDL no SoftC file handles available
SC_BADFNAME invalid filename
SC_NULLPARM parameter address null
SC_DBFVERS invalid dBase version
SC_DBFHLEN header length error
SC_DBFDATE last update date in error
Example Example _______
#include "SoftC.h"
void main()
{
char dbf;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS)
scdclose(dbf);
scterm();
}
scdrclear scdrclear _________
Usage Usage _____
signed short int scdrclear( signed char handle, scdrclear ______
signed short int buffer ); ______
Prototype in Prototype in ____________
dbase.h
40 Chapter 6, The SoftC Database Library 40
Description Description ___________
scdrclear clears a .DBF I/O buffer. buffer indicates scdrclear ______
which record buffer to clear.
buffer = clears this buffer
SC_INPUT input
SC_OUTPUT output
Return Value Return Value ____________
SC_SUCCESS buffer cleared
SC_BADHNDL .DBF file not open or bad handle
SC_BADCMD invalid buffer
Example Example _______
#include "SoftC.h"
void main()
{
char dbf, character[17] = "Hello World!";
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdfputs(dbf,0,"SoftC Library ");
scdrclear(dbf,SC_INPUT);
scdrcopy(dbf,SC_OUTPUT);
scdfgets(dbf,0,character);
printf("%s\n",character);
}
scterm();
}
scdrcopy scdrcopy ________
Usage Usage _____
signed short int scdrcopy( signed char handle, scdrcopy ______
signed short int buffer ); ______
Prototype in Prototype in ____________
dbase.h
Chapter 6, The SoftC Database Library 41 41
Description Description ___________
scdrcopy copies the contents of one I/O buffer to the scdrcopy
other. buffer indicates the direction of the copy. ______
buffer = copies this way
SC_INPUT input to output
SC_OUTPUT output to input
Return Value Return Value ____________
SC_SUCCESS buffer copy
SC_BADHNDL .DBF file not open or bad handle
SC_BADCMD invalid buffer
Example Example _______
#include "SoftC.h"
void main()
{
char dbf, character[17] = "Hello World!";
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdfputs(dbf,0,"SoftC Library ");
scdrclear(dbf,SC_INPUT);
scdrcopy(dbf,SC_OUTPUT);
scdfgets(dbf,0,character);
printf("%s\n",character);
scdclose(dbf);
}
scterm();
}
scdrdel scdrdel _______
Usage Usage _____
signed short int scdrdel( signed char handle, scdrdel ______
signed long int recno ); _____
Prototype in Prototype in ____________
dbase.h
42 Chapter 6, The SoftC Database Library 42
Description Description ___________
scdrdel will flag a record specified by recno as scdrdel _____
'deleted'. To maintain compatibility with dBaseIII the
data record cannot be reused, but it can be 'undeleted'
by scdrundel. scdrundel
See also See also ________
scdrundel. scdrundel
Return Value Return Value ____________
SC_SUCCESS record marked 'deleted'
SC_BADHNDL .DBF file not open or bad handle
SC_SKFAIL invalid data record number or disk seek
failure
SC_RDFAIL disk read failure
SC_WRTFAIL disk write failure
Example Example _______
#include "SoftC.h"
void main()
{
char dbf;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdrdel(dbf,1L);
scdrget(dbf,1L);
printf("%s\n",scemsg());
scdclose(dbf);
}
scterm();
}
scdrget scdrget _______
Usage Usage _____
signed short int scdrget( signed char handle, scdrget ______
signed long int recno ); _____
Chapter 6, The SoftC Database Library 43 43
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdrget will read the data record specified by recno scdrget _____
from the .DBF file associated with handle into the
internal input buffer.
See also See also ________
scdfget, scdfputs, scdrget. scdfget scdfputs scdrget
Return Value Return Value ____________
SC_SUCCESS record read
SC_BADHNDL .DBF file not open or bad handle
SC_SKFAIL invalid data record number or disk seek
failure
SC_RDFAIL disk read failure
SC_DELREC record read was marked 'deleted'
Example Example _______
#include "SoftC.h"
void main()
{
char dbf, character[17] = "Hello",
logical = 'F', date[9] = "12/25/88";
double numeric = 150.00L;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdrget(dbf,1L);
scdfgets(dbf,0,character);
scdfgets(dbf,1,date);
scdfget(dbf,2,(void *) &logical);
scdfget(dbf,3,(void *) &numeric);
printf("%s %s %c %lf\n",
character,date,logical,numeric);
scdclose(dbf);
}
scterm();
}
44 Chapter 6, The SoftC Database Library 44
scdrinfo scdrinfo ________
Usage Usage _____
signed short int scdrinfo( signed char handle, scdrinfo ______
signed short int *reclen, ______
signed char *numflds, _______
void **ibfr, ____
void **obfr ); ____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdrinfo gets the data record length (reclen), the scdrinfo ______
number of data fields per record (numflds), and the _______
addresses of the input (ibfr) and output (obfr) ____ ____
buffers.
Return Value Return Value ____________
SC_SUCCESS requested information returned
SC_BADHNDL .DBF file not open or bad handle
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char dbf, numflds;
short reclen;
void *ibfr, *obfr;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdrinfo(dbf,&reclen,&numflds,&ibfr,&obfr);
printf("Record length = %d\n",reclen);
printf("Number of fields = %d\n",numflds);
printf("I/O buffers = %p %p\n",ibfr,obfr);
scdclose(dbf);
}
scterm();
}
Chapter 6, The SoftC Database Library 45 45
scdrput scdrput _______
Usage Usage _____
signed short int scdrput( signed char handle, scdrput ______
signed short int howto, _____
signed long int *recno ); _____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdrput will write the data record specified by recno scdrput _____
to the .DBF file associated with handle from the ______
internal output buffer. howto determines how the data _____
record is to be written:
howto = action
SC_ADD record appended to end of file
SC_UPDATE current record updated
If a record update is occurring the data record number
associated with the record in the input buffer will be
returned. An update will not be performed if the input
buffer is empty. Use scdrget to load a data record or scdrget
scdfput or scdfputs to fill the data record field by scdfput scdfputs
field.
See also See also ________
scdfput, scdfputs, scdrget. scdfput scdfputs scdrget
Return Value Return Value ____________
SC_SUCCESS record read
SC_BADHNDL .DBF file not open or bad handle
SC_SKFAIL invalid data record number or disk seek
failure
SC_WRTFAIL disk write failure
SC_BADCMD invalid record write command
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
46 Chapter 6, The SoftC Database Library 46
void main()
{
char dbf, logical = 'T', date[9] = "19881225";
long recno;
double numeric = 20.0L;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdfputs(dbf,0,"SoftC Library ");
scdfput(dbf,1,(void *) date);
scdfput(dbf,2,(void *) &logical);
scdfput(dbf,3,(void *) &numeric);
scdrput(dbf,SC_ADD,&recno);
printf("Record number = %ld\n",recno);
scdclose(dbf);
}
scterm();
}
scdrundel scdrundel _________
Usage Usage _____
signed short int scdrundel( signed char handle, scdrundel ______
signed long int recno ); _____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdrundel will remove the 'deleted' flag from the data scdrundel
record specified by recno. _____
See also See also ________
scdrdel. scdrdel
Return Value Return Value ____________
SC_SUCCESS record recovered
SC_BADHNDL .DBF file not open or bad handle
SC_SKFAIL invalid data record number or disk seek
failure
SC_RDFAIL disk read failure
SC_WRTFAIL disk write failure
Chapter 6, The SoftC Database Library 47 47
Example Example _______
#include "SoftC.h"
void main()
{
char dbf;
long recno;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdrundel(dbf,1L);
scdrget(dbf,1L);
printf("%s\n",scemsg());
scdclose(dbf);
}
scterm();
}
scdsize scdsize _______
Usage Usage _____
signed short int scdsize( signed char handle, scdsize ______
signed long int *recsused ); ________
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scdsize gets the number of records in the .DBF file. scdsize
Return Value Return Value ____________
SC_SUCCESS returned the number of records
SC_BADHNDL .DBF file not open or bad handle
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
48 Chapter 6, The SoftC Database Library 48
void main()
{
char dbf;
long recsused;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
scdsize(dbf,&recsused);
printf("%ld",recsused);
scdclose(dbf);
}
scterm();
}
sceclr sceclr ______
Usage Usage _____
void sceclr( void ); sceclr
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
sceclr will clear the SoftC library error flag sceclr
(sc_code). sc_code
See also See also ________
scemsg. scemsg
Return Value Return Value ____________
None.
Example Example _______
#include "SoftC.h"
void main()
{
scinit(20);
sceclr();
Chapter 6, The SoftC Database Library 49 49
scterm();
}
scemsg scemsg ______
Usage Usage _____
signed char * scemsg( void ); scemsg
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
scemsg gets the SoftC library error message which scemsg
corresponds to the last known error.
Warning Codes and Messages:
1 "WARNING - record read is marked deleted",
2 "WARNING - file is empty",
3 "WARNING - no more keys",
4 "WARNING - could not find key in index file",
5 "WARNING - data field truncated",
6 "WARNING - numeric field rounded",
7 "WARNING - memo fields not supported",
8 "WARNING - file length is incorrect"
Error Codes and Messages:
-1 "ERROR - file write failure",
-2 "ERROR - file read failure",
-3 "ERROR - memory allocation error",
-4 "ERROR - bad user specified field description",
-5 "ERROR - file not in .DBF format",
-6 "ERROR - file pointer reposition failed",
-7 "ERROR - file not found",
-8 "ERROR - file corrupted",
-9 "ERROR - bad user specified key expression",
-10 "ERROR - file not in .NDX format",
-11 "ERROR - no handles available",
-12 "ERROR - no index pages loaded",
-13 "ERROR - index page was not loaded",
50 Chapter 6, The SoftC Database Library 50
-14 "ERROR - file close failure",
-15 "ERROR - invalid command",
-16 "ERROR - invalid handle number",
-17 "ERROR - invalid filename",
-18 "ERROR - invalid date",
-19 "ERROR - invalid time",
-20 "ERROR - file not in .DBT format",
-21 "ERROR - invalid dBaseIII version",
-22 "ERROR - file header length error",
-23 "ERROR - last file change date in error",
-24 "ERROR - parameter address null",
-25 "ERROR - invalid key type",
-26 "ERROR - invalid key length",
-27 "ERROR - item length incorrect",
-28 "ERROR - invalid root page",
-29 "ERROR - bad maximum number of keys per page"
See also See also ________
sceclr. sceclr
Return Value Return Value ____________
scemsg returns the error message. scemsg
Example Example _______
#include "SoftC.h"
void main()
{
scinit(20);
printf("%s",scemsg());
scterm();
}
sciclose sciclose ________
Usage Usage _____
signed short int sciclose( signed char handle ); sciclose ______
Prototype in Prototype in ____________
dbase.h
Chapter 6, The SoftC Database Library 51 51
Description Description ___________
sciclose closes an .NDX file and frees all allocated sciclose
memory associated with .NDX file.
Return Value Return Value ____________
SC_SUCCESS .NDX file closed
SC_CLOSFAIL file close failure
SC_BADHNDL .NDX file not open or bad handle
Example Example _______
#include "SoftC.h"
void main()
{
char ndx;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS)
sciclose(ndx);
scterm();
}
scicreate scicreate _________
Usage Usage _____
signed short int scicreate( signed char *filename, scicreate ________
signed char keytype, _______
signed char *keyexpr, _______
signed char keylen ); ______
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scicreate creates an .NDX file. keyexpr will be scicreate _______
translated to all upper case when the index file is
created.
If keytype is 'c', then keyexpr must be a character _______ _______
string consisting of one or more field names from the
52 Chapter 6, The SoftC Database Library 52
data record. All fields included in the expression must
be of type 'c' or be translated into type 'c'. No check
is made to verify this. keylen cannot exceed 100. ______
If keytype is 'n' or 'd', then keyexpr should consist _______ _______
of only one data field. keylen will automatically be ______
set to 8 (numeric and date keys are stored as doubles).
NOTE: scicreate will create a new .NDX file even if one scicreate
had already existed.
NOTE: keyexpr is used by dBaseIII. keyexpr is NOT _______ _______
checked for validity by the SoftC data file manager.
Currently only the scikmake function uses keyexpr. scikmake _______
See also See also ________
scikmake. scikmake
Return Value Return Value ____________
SC_SUCCESS .NDX file created
SC_WRTFAIL disk write failure
SC_BADEXPR invalid keytype or bad keyexpr
SC_NOHNDL no DOS handles available
SC_NULLPARM parameter address null
SC_BADKEYT invalid key type
SC_KEYLEN invalid key length
Example Example _______
#include "SoftC.h"
void main()
{
scinit(20);
scicreate("TEST.NDX",'d',"date",8);
scterm();
}
Chapter 6, The SoftC Database Library 53 53
sciexpr sciexpr _______
Usage Usage _____
signed short int sciexpr( signed char handle, sciexpr ______
signed char *keyexpr ); _______
Prototype in Prototype in ____________
dbase.h
Description Description ___________
sciexpr gets the index key expression and returns it as sciexpr
a character string into a user supplied buffer
(keyexpr). The user must ensure that the buffer is _______
large enough (the key expression length can be
determined via a call to sciinfo) to hold the entire sciinfo
key expression.
See also See also ________
sciinfo. sciinfo
Return Value Return Value ____________
SC_SUCCESS returned the keyexpr
SC_BADHNDL .NDX file not open or bad handle
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char ndx, buffer[512];
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
sciexpr(ndx,buffer);
printf("key expression = %s",buffer);
sciclose(ndx);
}
scterm();
}
54 Chapter 6, The SoftC Database Library 54
sciinfo sciinfo _______
Usage Usage _____
signed short int sciinfo( signed char handle, sciinfo ______
signed char *filename, ________
signed char *keytype, _______
signed char *keylen, ______
signed short int *exprlen ); __________
Prototype in Prototype in ____________
dbase.h
Description Description ___________
sciinfo gets the filename of the .NDX file associated sciinfo
with handle, the index key type (keytype), the maximum ______ _______
index key length (keylen), and the length of the index
key expression (exprlen).
See also See also ________
sciopen. sciopen
Return Value Return Value ____________
SC_SUCCESS returned .NDX file information
SC_BADHNDL .NDX file not open or bad handle
SC_NULLPARM parameter address null
Example Example _______
#include <dir.h>
#include "SoftC.h"
void main()
{
char ndx, filename[MAXPATH], keytype, keylen, exprlen;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
sciinfo(ndx,filename,&keytype,&keylen,&exprlen);
printf("File name = %s\n",filename);
printf("Index key type = %c\n",keytype);
printf("Maximum key length = %d\n",keylen);
printf("Key expression length = %d\n",exprlen);
sciclose(ndx);
}
Chapter 6, The SoftC Database Library 55 55
scterm();
}
scikadd scikadd _______
Usage Usage _____
signed short int scikadd( signed char handle, scikadd ______
signed char *key, ___
signed long int recno ); _____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scikadd will add key to the index file specified by scikadd ___
handle. recno is the data record number to be _____
associated with key (the data record pointed to by ___
recno must exist prior to calling scikadd). scikadd
See also See also ________
scikmake. scikmake
Return Value Return Value ____________
SC_SUCCESS key added to .NDX file
SC_BADHNDL .NDX file not open or bad handle
SC_SKFAIL disk seek failure
SC_WRTFAIL disk write failure
SC_RDFAIL disk read failure
SC_MEMERR memory allocation failure
SC_NULLPARM parameter address null
Example Example _______
#include <string.h>
#include "SoftC.h"
void main()
{
char dbf, ndx, date[9];
short result;
long recno;
56 Chapter 6, The SoftC Database Library 56
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
strcpy(date,"19881201");
scdfputs(dbf,1,date);
result = scdrput(dbf,SC_ADD,&recno)
if (result == SC_SUCCESS)
scikadd(ndx,date,recno);
sciclose(ndx);
}
scdclose(dbf)
}
scterm();
}
scikcur scikcur _______
Usage Usage _____
signed short int scikcur( signed char handle, scikcur ______
signed char *key, ___
signed long int *recno ); _____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scikcur will return the key value (key) and data record scikcur ___
number (recno) associated with the current key in the _____
index file.
The current key pointer must be set by a call to either
scikfind, scikfirst, or sciklast before calling scikfind scikfirst sciklast
scikcur. scikcur
The user must ensure that the buffer used to return the
key is large enough to hold the entire key. The maximum
length of the key can be determined via a call to
sciinfo. sciinfo
See also See also ________
sciinfo, scikfind, scikfirst, and sciklast. sciinfo scikfind scikfirst sciklast
Chapter 6, The SoftC Database Library 57 57
Return Value Return Value ____________
SC_SUCCESS key and recno returned
SC_BADHNDL .NDX file not open or bad handle
SC_END no current key - no call to scikfind, scikfind
scikfirst, or sciklast had been made to scikfirst, sciklast
initialize the index pointers.
SC_RDFAIL read index file failure
SC_SKFAIL seek failure (bad record address or seek
fail)
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char ndx, date[9], dat[9];
long recno, rnum;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
date[8] = 0;
dat[8] = 0;
scikfirst(ndx,date,&recno);
scikcur(ndx,dat,&rnum);
printf("%s %s %ld %ld\n",
date,dat,recno,rnum);
sciclose(ndx);
}
scterm();
}
scikdel scikdel _______
Usage Usage _____
signed short int scikdel( signed char handle, scikdel ______
signed char *key, ___
signed long int recno ); _____
Prototype in Prototype in ____________
dbase.h
58 Chapter 6, The SoftC Database Library 58
Description Description ___________
scikdel will remove key from the index file specified scikdel ___
by handle. recno is used along with key to ensure that ______ _____
the proper key has been removed from the .NDX file.
Return Value Return Value ____________
SC_SUCCESS key removed from .NDX file
SC_BADHNDL .NDX file not open or bad handle
SC_SKFAIL disk seek failure
SC_WRTFAIL disk write failure
SC_RDFAIL index file read failure
SC_EMPTY index file is empty - no keys found
SC_NOFIND desired key was not found
SC_NULLPARM parameter address null
Example Example _______
#include <string.h>
#include "SoftC.h"
void main()
{
char ndx, date[9];
long recno;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
strcpy(date,"19881202");
recno = 7L;
scikdel(ndx,date,recno);
sciclose(ndx);
}
scterm();
}
scikfind scikfind ________
Usage Usage _____
signed short int scikfind( signed char handle, scikfind ______
signed char method, ______
signed char *key, ___
signed long int *recno ); _____
Chapter 6, The SoftC Database Library 59 59
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scikfind supports two key search methods (determined by scikfind
method): SC_EXACT - find an exact match with key and ______ ___
recno, and SC_FIRST - find the first logical occurrence _____
of key in the index and return the associated recno if ___ _____
found.
If a match cannot be found, the current key will be the
physical key which would immediately precede key. The ___
current key's value and data record number will be
returned in key and recno. ___ _____
The user must ensure that the buffer used to return the
key is large enough to hold the entire key. The maximum
length of the key can be determined via a call to
sciinfo. sciinfo
See also See also ________
sciinfo. sciinfo
Return Value Return Value ____________
SC_SUCCESS key found
SC_NOFIND key not found
SC_EMPTY .NDX file empty - no keys found
SC_BADHNDL .NDX file not open or bad handle
SC_SKFAIL seek failure (bad record address or seek
fail)
SC_RDFAIL read index file failure
SC_END end of index file
SC_NULLPARM parameter address null
Example Example _______
#include <string.h>
#include "SoftC.h"
void main()
{
char ndx, key[100];
long recno;
int result;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
60 Chapter 6, The SoftC Database Library 60
strcpy(date,"19881202");
recno = 7L;
scikfind(ndx,SC_EXACT,date,&recno);
printf("%s\n",scemsg());
scdclose(ndx);
}
scterm();
}
scikfirst scikfirst _________
Usage Usage _____
signed short int scikfirst( signed char handle, scikfirst ______
signed char *key, ___
signed long int *recno ); _____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scikfirst will set the current key pointer to the first scikfirst
logical key in the .NDX and return the key value (key) ___
and data record number (recno) associated with the new _____
current key.
The user must ensure that the buffer used to return the
key is large enough to hold the entire key. The maximum
length of the key can be determined via a call to
sciinfo. sciinfo
See also See also ________
sciinfo sciinfo
Return Value Return Value ____________
SC_SUCCESS key and recno returned
SC_BADHNDL .NDX file not open or bad handle
SC_EMPTY .NDX file empty - no keys found
SC_SKFAIL seek failure
SC_RDFAIL read index file failure
SC_NULLPARM parameter address null
Chapter 6, The SoftC Database Library 61 61
Example Example _______
#include "SoftC.h"
void main()
{
char ndx, date[9];
long recno;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
date[8] = 0;
scikfirst(ndx,date,&recno);
printf("%d %ld\n",date,recno);
sciclose(ndx);
}
scterm();
}
sciklast sciklast ________
Usage Usage _____
signed short int sciklast( signed char handle, sciklast ______
signed char *key, ___
signed long int *recno ); _____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
sciklast will set the current key pointer to the last sciklast
logical key in the .NDX and return the key value (key)
and data record number (recno) associated with the new
current key.
The user must ensure that the buffer used to return the
key is large enough to hold the entire key. The maximum
length of the key can be determined via a call to
sciinfo. sciinfo
62 Chapter 6, The SoftC Database Library 62
See also See also ________
sciinfo;. sciinfo;.
Return Value Return Value ____________
SC_SUCCESS key and recno returned
SC_BADHNDL .NDX file not open or bad handle
SC_EMPTY .NDX file empty - no keys found
SC_SKFAIL seek failure
SC_RDFAIL read from index file failure
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char ndx, date[9];
long recno;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
date[8] = 0;
sciklast(ndx,date,&recno);
printf("%s %ld\n",date,recno);
sciclose(ndx);
}
scterm();
}
scikmake scikmake ________
Usage Usage _____
signed short int scikmake( signed char datahandle, scikmake __________
signed char indexhandle, ___________
void **key ); ___
Prototype in Prototype in ____________
dbase.h
Chapter 6, The SoftC Database Library 63 63
Description Description ___________
scikmake will build an index key using the key scikmake
expression of the index file specified by indexhandle ___________
and the data found in the output buffer of the data
file of datahandle. Memory space for the key will be __________ ___
allocated and the address of this block will be
returned.
The key expression can consist of either the data field
name or one of five dBaseIII functions or a combination
thereof. Data field types of date, numeric, or
character are allowed. dBaseIII functions dtoc, left, dtoc left
right, str, and substr are current supported by right str substr
scikmake. scikmake
dBaseIII supports only two types of keys: character and
numeric. The only numeric keys supported by SoftC are
just the date and numeric data field names.
dtoc will convert data from a date field to a character dtoc
string of the format mm/dd/yy. Syntax is
dtoc(field_name).
left will return the left portion of a character field left
as a string. The number of characters returned is
specified after the field name. Syntax is
left(field_name,number).
right will return the right portion of a character right
field as a string. The number of characters returned is
specified after the field name. This is a count from
the right side of the field. Syntax is
right(field_name,count).
str will convert a numeric field to an ascii string. str
The total length of the string and the number of
decimal places are optional parameters. The default
string length is 10 and the number of decimal places is
0. Syntax is str(field_name,length,decimal_places).
substr will return the middle portion of a character substr
field. The starting offset into the field is a required
parameter. The number of characters to be used is an
optional parameter whose default value is the remainder
of the field. Syntax is substr(field_name,start,count).
64 Chapter 6, The SoftC Database Library 64
An example of a more complex key expression:
right(dtoc(date),2)+left(dtoc(date,2)
This expression would cause scikmake to create an index scikmake
key string consisting of the year and month ("yymm").
For example if date equals "2/13/89" the resultant key
would be "8902".
Note that for key expressions consisting of only one
numeric or character data field scikmake is probably an scikmake
overkill. You can easily generate these keys yourself.
scikmake is a fairly large module and if not needed scikmake
probably should not be used. This function is best used
for date keys or when the key expression is more
complex.
See also See also ________
scicreate. scicreate
Return Value Return Value ____________
SC_SUCCESS key and recno returned
SC_BADHNDL .NDX file not open or bad handle
SC_MEMERR memory allocation failure
SC_BADEXPR invalid key expression
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char ndx, dbf, char *key, date[9];
long recno;
scinit(20);
if (scdopen(&dbf,"TEST.DBF") == SC_SUCCESS) {
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
scdfput(dbf,0,&date);
scdrput(dbf,SC_ADD,&recno);
scikmake(dbf,ndx,(void **) &key);
scikadd(ndx,key,recno);
free(key);
sciclose(ndx);
}
Chapter 6, The SoftC Database Library 65 65
scdclose(dbf);
}
scterm();
}
sciknext sciknext ________
Usage Usage _____
signed short int sciknext( signed char handle, sciknext ______
signed char *key, ___
signed long int *recno ); _____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
sciknext will increment the key pointer and return the sciknext
key value (key) and data record number (recno) ___ _____
associated with the new current key.
The current key pointer must be set by a call to either
scikfind, scikfirst, or sciklast before calling scikfind scikfirst sciklast
sciknext. sciknext
The user must ensure that the buffer used to return the
key is large enough to hold the entire key. The maximum
length of the key can be determined via a call to
sciinfo. sciinfo
See also See also ________
sciinfo, scikfind, scikfirst, and sciklast. sciinfo scikfind scikfirst sciklast
Return Value Return Value ____________
SC_SUCCESS key and recno returned
SC_BADHNDL .NDX file not open or bad handle
SC_END no more keys - at end of .NDX file
SC_RDFAIL index file read failure
SC_SKFAIL seek failure (bad record address or seek
failed)
SC_NULLPARM parameter address null
66 Chapter 6, The SoftC Database Library 66
Example Example _______
#include "SoftC.h"
void main()
{
char ndx, date[9];
long recno;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
scikfirst(ndx,date,&recno);
sciknext(ndx,date,&recno);
printf("%s %ld\n",date,recno);
sciclose(ndx);
}
scterm();
}
scikprev scikprev ________
Usage Usage _____
signed short int scikprev( signed char handle, scikprev ______
signed char *key, ___
signed long int *recno ); _____
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scikprev will decrement the key pointer and return the scikprev
key value (key) and data record number (recno) ___ _____
associated with the new current key.
The current key pointer must be set by a call to either
scikfind, scikfirst, or sciklast before calling scikfind scikfirst sciklast
scikprev. scikprev
The user must ensure that the buffer used to return the
key is large enough to hold the entire key. The maximum
Chapter 6, The SoftC Database Library 67 67
length of the key can be determined via a call to
sciinfo. sciinfo
See also See also ________
sciinfo, scikfind, scikfirst, and sciklast. sciinfo scikfind scikfirst sciklast
Return Value Return Value ____________
SC_SUCCESS key and recno returned
SC_BADHNDL .NDX file not open or bad handle
SC_END no more keys - at end of .NDX file
SC_RDFAIL index file read failure
SC_SKFAIL index file record seek failure
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char ndx, date[9];
long recno;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
sciklast(ndx,date,&recno);
scikprev(ndx,date,&recno);
printf("%s %ld\n",date,recno);
sciclose(ndx);
}
scterm();
}
scinit scinit ______
Usage Usage _____
signed short int scinit( signed char files ); scinit _____
Prototype in Prototype in ____________
SoftC.h
68 Chapter 6, The SoftC Database Library 68
Description Description ___________
scinit is called once and only once at the beginning of scinit
the program. The maximum number of simultaneously open
files is passed. This function sets up the SoftC _____
environment for processing. Memory will be allocated
for a variety of control structures used internally by
the SoftC manager.
See also See also ________
scterm. scterm
Return Value Return Value ____________
SC_SUCCESS completed initialization
SC_MEMERR memory allocation failure
SC_BADHNDL invalid number of handles
Example Example _______
#include "SoftC.h"
void main()
{
scinit(20);
scterm();
}
sciopen sciopen _______
Usage Usage _____
signed short int sciopen( signed char *handle, sciopen ______
signed char *filename ); ________
Prototype in Prototype in ____________
dbase.h
Description Description ___________
sciopen opens an .NDX file. Memory will be allocated sciopen
for a file packet, I/O buffers, and other miscellaneous
structures for use internally by the SoftC file
manager.
Chapter 6, The SoftC Database Library 69 69
Return Value Return Value ____________
SC_SUCCESS .NDX file opened
SC_MEMERR memory allocation failure
SC_NOFILE .NDX file not found
SC_RDFAIL disk read failure
SC_NONDX file not in .NDX format
SC_SKFAIL disk seek failure
SC_NOHNDL no SoftC handles available
SC_BADFNAME invalid filename
SC_NULLPARM parameter address null
SC_KEYLEN invalid key length
SC_ITEMLEN invalid key item length
SC_BADROOT invalid root page number
SC_MAXKEYS bad maximum number of keys
SC_FILENGTH invalid file length
Example Example _______
#include "SoftC.h"
void main()
{
char ndx;
scinit(20);
if (sciopen(&ndx,"UNKNOWN.NDX") == SC_SUCCESS) {
sciclose(ndx);
}
scterm();
}
scipinfo scipinfo ________
Usage Usage _____
signed short int scipinfo( signed char handle, scipinfo ______
signed char *numpgs ); ______
Prototype in Prototype in ____________
dbase.h
70 Chapter 6, The SoftC Database Library 70
Description Description ___________
scipinfo gets the maximum number of index pages the scipinfo
SoftC file manager can keep in memory and returns it
via numpgs. ______
Return Value Return Value ____________
SC_SUCCESS max number of pages allowed returned
SC_BADHNDL .NDX file not open or bad handle
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char ndx, numpgs;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
scipinfo(ndx,&numpgs) == SC_SUCCESS)
printf("Maximum number of pages = %d\n",numpgs);
sciclose(ndx);
}
scterm();
}
scipnum scipnum _______
Usage Usage _____
signed short int scipnum( signed char handle, scipnum ______
signed char *numpgs ); ______
Prototype in Prototype in ____________
dbase.h
Description Description ___________
scipnum sets the maximum number of index pages (numpgs) scipnum ______
the SoftC file manager can keep in memory. Memory for
index pages will be freed or allocated as appropriate.
Chapter 6, The SoftC Database Library 71 71
Return Value Return Value ____________
SC_SUCCESS new max number of pages allowed returned
SC_BADHNDL .NDX file was open or bad handle
SC_BADCMD invalid new number of pages requested
SC_NULLPARM parameter address null
Example Example _______
#include "SoftC.h"
void main()
{
char ndx, numpgs = 5;
scinit(20);
if (sciopen(&ndx,"TEST.NDX") == SC_SUCCESS) {
scipnum(ndx,&numpgs);
scipinfo(ndx,&numpgs);
printf("New max = %d\n",numpgs);
sciclose(ndx);
}
scterm();
}
scterm scterm ______
Usage Usage _____
signed short int scterm( void ); scterm
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
scterm is called once at the end of the program. Memory scterm
allocated by scinit for internal control structures scinit
will be freed. All files open will be closed and any
memory allocated for them will be freed.
See also See also ________
scinit. scinit
72 Chapter 6, The SoftC Database Library 72
Return Value Return Value ____________
SC_SUCCESS completed initialization
Example Example _______
#include "SoftC.h"
void main()
{
scinit(20);
scterm();
}
scvers scvers ______
Usage Usage _____
signed char * scvers( void ); scvers
Prototype in Prototype in ____________
SoftC.h
Description Description ___________
scvers gets the SoftC library revision in the form of a scvers
character string.
Return Value Return Value ____________
scvers returns the library revision. scvers
Example Example _______
#include "SoftC.h"
void main()
{
scinit(20);
printf("SoftC Database Library Revision %s",scvers());
scterm();
}
LICENSE
SoftC Database Library is Copyright (c) 1988, 1989 by K. Schumann. SoftC
SoftC Window Library is Copyright (c) 1988, 1989 by L. Olson and K. SoftC
Schumann.
The SoftC libraries are not, nor have they ever been, public domain or SoftC
free software. The author(s) of the SoftC library(s) retain all rights SoftC
to the source and object code. Distribution of SoftC library source or SoftC
object files without prior written consent from K. Schumann is
considered theft and as such will be prosecuted.
The SoftC libraries are distributed under the user supported SoftC
(shareware) software concept. Non-registered users of the library(s)
are granted a limited license to use SoftC for a trial period, in SoftC
order to determine if it suits their needs. Any other use of SoftC or SoftC
use beyond this trial period requires registration. Any use of non-
registered copies of a SoftC library by a business, organization, or SoftC
any kind of institution is forbidden.
A registered copy of a SoftC library must be treated like a book. Like SoftC
a book, the same registered copy of SoftC may not be used in more than SoftC
one computer at the same time. Registered users of SoftC are granted a SoftC
limited license to include library object code in their products.
All users are granted a limited license to copy the SoftC library SoftC
evaluation kit in an absolutely unmodified form (small memory model
object library(s), library header file(s), library reference manual,
READ.ME, license agreement, and order form) for the purpose of
allowing others to try it.
Bulletin Board system operators may post SoftC on their BBS for SoftC
downloading by their users without written permission only if the
above conditions are met, and only if no special fee is necessary to
access the SoftC library files (a general fee to access the BBS is SoftC
acceptable).
Distributors of shareware and public domain software MUST obtain
written permission from K. Schumann before distributing a SoftC SoftC
library evaluation kit and must follow the above conditions. This is
to ensure that the library files being distributed are complete and
unmodified.
SoftC Libraries Invoice #051089 SoftC
**************************************************************************
Remit to : K. Schumann, 16820 3rd St NE, Ham Lake, MN 55304
**************************************************************************
Database Windows Item US/Canada Price
_______ _______ SoftC Source Registration $100/$125 ea $________ SoftC Source Registration 100 125
(includes full commented source and all
compiler memory models)
_______ _______ SoftC Object Registration $20/$25 ea $________ SoftC Object Registration 20 25
(includes all compiler memory models)
_______ _______ SoftC Evaluation Disk $10/$12 ea $________ SoftC Evaluation Disk 10 12
(does not include registration)
_______ _______ SoftC Source Update $35/$44 ea $________ SoftC Source Update 35 44
_______ _______ SoftC Object Update $15/$19 ea $________ SoftC Object Update 15 19
Subtotal $________
Minnesota residents please add 6% sales tax. Tax $________
Total $________
Check or money order only. Prices subject to change without notice.
Library reference manual and other documentation is included on disk.
Registered users are entitled to one free update.
**************************************************************************
I, the undersigned, have read and understood the terms of the license
agreement (LICENSE.DOC) and agree to be bound by its conditions.
Signature_________________________________________________________________
Name______________________________________________________________________
Company___________________________________________________________________
Address___________________________________________________________________
City______________________________________State_________Zip_______________
Phone (______)_____________________ Bus. (______)_____________________
Compiler Vendor_______________________________ Version____________________
Where did you obtain SoftC?_______________________________________________ SoftC
Comments__________________________________________________________________
__________________________________________________________________________
__________________________________________________________________________
Appendix C Appendix C
Revision History Revision History
v1.00 (December of 1988) v1.00 (December of 1988)
Initial release of library. Included dBaseIII+ data and index
file access routines (including individual record and field
access functions), and text windowing and related functions.
v1.01 (February of 1989) v1.01 (February of 1989)
Fixes for 5 problems included:
1) Could not properly access fields whose offset in the data
record is beyond 128. Error functions: scdfget, scdfgets, scdfget scdfgets
scdfput, scdfputs. scdfput scdfputs
2) Could not properly store data in a numeric field when zero
was specified for number of decimal places. Error function:
scdfput. scdfput
3) Could not correctly find the first item of a LONG list of LONG
items using the same index key value. Error function: scikfind. scikfind
4) Did not correctly set the text colors after the last window
had been closed. Error function: scwclose. scwclose
5) Could not open dBaseIII+ data and index files properly. Was
able to open Clipper and dBC3+ files. dBaseIII+, Clipper, and
dBC3+ could open files created by library. Error functions:
scdopen, sciopen. scdopen sciopen
Thirteen new functions were added to the library: an error clear
(sceclr), cursor on/off (scwcurson, scwcursoff), a powerful index sceclr scwcurson scwcursoff
key builder (scikmake), and 9 date functions. scikmake
The date functions include: week day (sccday) and month sccday
(sccmonth) string return functions, 2 leap year testing routines sccmonth
- one for a string (sccleap) and the other for an integer sccleap
(sccleapi), a date string validation function (sccdvalid), two sccleapi sccdvalid
date translation functions: one to convert from integers to
76 Appendix C, Revision History 76
"yyyymmdd" strings (sccdn2s) and vice versa (sccds2n), and sccdn2s sccds2n
another to convert between "yyyymmdd" and "mm/dd/yy" or
"mm/dd/yyyy" strings (sccdxlat), and the last function to sccdxlat
calculate the difference in days between two date strings
(sccddiff). sccddiff
Function scdcreate was modified to allow only 19 characters scdcreate
maximum for numeric fields. This brought the function in line
with dBaseIII+.
The way scdfget and scdfput handled date fields was changed to scdfget scdfput
use a nine character string formatted as "mm/dd/yy".
Also I publicized my GEnie GEMail address as another method
whereby I could be contacted.
v1.02 (April of 1989) v1.02 (April of 1989)
Due to numerous problems found in scikadd and scikdel, these scikadd scikdel
functions were completely rewritten. One new function was added
to the library: sccds2l which translates string dates to longs. sccds2l
This function was originally part of sccddiff. sccddiff
Error checking was tightened. Most functions now check for NULL
pointers as passed parameters. Certain errors such as file length
have been changed to warnings. Additional errors have been
defined to pinpoint the failure more closely, especially in
scdopen and sciopen, but this affects many other functions as scdopen sciopen
well.
The "text window" functions were removed from this library
because its focus was narrowed to dBaseIII+ compatible file
access. Many users expressed a desire to use their own favorite
windows toolkit. The window functions have been placed in their
own library, and menu and atgets have been added.
Registration fees were changed to better reflect the value of the
toolkit. Object code level registration is $20, and source code
level is $100.
Microsoft C v5.1 was now supported along with Quick C v2.0.
The number of header files was reduced to one.
Appendix C, Revision History 77 77
An extensive suite of tests were written to enable better
debugging of future versions of the library.
v1.03 (May of 1989) v1.03 (May of 1989)
Three problems were corrected:
1) May or may not be able to find a particular numeric (or
date) key when searching the index file b-tree. This problem also
affected adding numeric (and date) keys to an index file. Error
function: scikfind. scikfind
2) Date keys were not being built properly by scikmake. Index scikmake
key being built was not compatible with dBase III+. Error
function: scikmake. scikmake
3) Minor problem when releasing unused index pages. Failure
would not occur under normal operating conditions. Error
function: scikdel. scikdel
INDEX
dtoc 12, 63 scikfirst 11, 56, 57, 60,
left 12, 63 65, 66, 67
right 12, 63 sciklast 11, 56, 57, 61,
sc_code 15, 16, 48 65, 66, 67
sccday 13, 18, 26, 75 scikmake 12, 52, 55, 62,
sccddiff 13, 19, 76 63, 64, 75, 77
sccdn2s 13, 19, 20, 22, 76 sciknext 11, 65
sccds2l 13, 21, 76 scikprev 11, 66
sccds2n 13, 20, 21, 22, 76 scinit 2, 5, 15, 67, 68,
sccdvalid 14, 19, 20, 22, 71
23, 75 sciopen 11, 54, 68, 75, 76
sccdxlat 13, 19, 23, 76 scipinfo 11, 69, 70
sccleap 14, 24, 25, 75 scipnum 11, 70
sccleapi 14, 24, 25, 75 scterm 5, 9, 15, 68, 71
sccmonth 13, 18, 26, 75 scvers 15, 72
scdclose 9, 27 str 12, 63
scdcreate 9, 10, 28, 76 substr 12, 63
scdfget 10, 29, 30, 31,
35, 36, 43, 75, 76
scdfgets 10, 30, 31, 36,
37, 75
scdfinfo 30, 31, 32, 33
scdfnam2no 11, 34
scdfput 10, 30, 35, 36,
37, 45, 75, 76
scdfputs 10, 31, 35, 36,
43, 45, 75
scdinfo 9, 37, 38
scdopen 9, 27, 38, 39, 75,
76
scdrclear 10, 39, 40
scdrcopy 10, 40, 41
scdrdel 10, 41, 42, 46
scdrget 9, 30, 31, 42, 43,
45
scdrinfo 10, 33, 44
scdrput 9, 45
scdrundel 10, 42, 46
scdsize 9, 47
sceclr 15, 48, 50, 75
scemsg 15, 48, 49, 50
sciclose 11, 50, 51
scicreate 11, 51, 52, 64
sciexpr 11, 53
sciinfo 11, 53, 54, 56,
59, 60, 61, 62, 65, 67
scikadd 12, 55, 76
scikcur 12, 56
scikdel 12, 57, 58, 76, 77
scikfind 11, 56, 57, 58,
59, 65, 66, 67, 75, 77
78
